home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / idl / nsIPipe.idl < prev    next >
Text File  |  2006-05-08  |  9KB  |  212 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is mozilla.org code.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26.  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38. #include "nsIAsyncInputStream.idl"
  39. #include "nsIAsyncOutputStream.idl"
  40.  
  41. interface nsIMemory;
  42.  
  43. /**
  44.  * nsIPipe represents an in-process buffer that can be read using nsIInputStream
  45.  * and written using nsIOutputStream.  The reader and writer of a pipe do not
  46.  * have to be on the same thread.  As a result, the pipe is an ideal mechanism
  47.  * to bridge data exchange between two threads.  For example, a worker thread
  48.  * might write data to a pipe from which the main thread will read.
  49.  *
  50.  * Each end of the pipe can be either blocking or non-blocking.  Recall that a
  51.  * non-blocking stream will return NS_BASE_STREAM_WOULD_BLOCK if it cannot be
  52.  * read or written to without blocking the calling thread.  For example, if you
  53.  * try to read from an empty pipe that has not yet been closed, then if that
  54.  * pipe's input end is non-blocking, then the read call will fail immediately
  55.  * with NS_BASE_STREAM_WOULD_BLOCK as the error condition.  However, if that
  56.  * pipe's input end is blocking, then the read call will not return until the
  57.  * pipe has data or until the pipe is closed.  This example presumes that the
  58.  * pipe is being filled asynchronously on some background thread.
  59.  *
  60.  * The pipe supports nsIAsyncInputStream and nsIAsyncOutputStream, which give
  61.  * the user of a non-blocking pipe the ability to wait for the pipe to become
  62.  * ready again.  For example, in the case of an empty non-blocking pipe, the
  63.  * user can call AsyncWait on the input end of the pipe to be notified when 
  64.  * the pipe has data to read (or when the pipe becomes closed).
  65.  *
  66.  * NS_NewPipe2 and NS_NewPipe provide convenient pipe constructors.  In most
  67.  * cases nsIPipe is not actually used.  It is usually enough to just get
  68.  * references to the pipe's input and output end.  In which case, the pipe is
  69.  * automatically closed when the respective pipe ends are released.
  70.  */
  71. [scriptable, uuid(f4211abc-61b3-11d4-9877-00c04fa0cf4a)]
  72. interface nsIPipe : nsISupports
  73. {
  74.     /**
  75.      * initialize this pipe
  76.      */
  77.     void init(in boolean nonBlockingInput,
  78.               in boolean nonBlockingOutput,
  79.               in unsigned long segmentSize,
  80.               in unsigned long segmentCount,
  81.               in nsIMemory segmentAllocator);
  82.  
  83.     /**
  84.      * The pipe's input end, which also implements nsISearchableInputStream.
  85.      */
  86.     readonly attribute nsIAsyncInputStream inputStream;
  87.  
  88.     /**
  89.      * The pipe's output end.
  90.      */
  91.     readonly attribute nsIAsyncOutputStream outputStream;
  92. };
  93.  
  94. /**
  95.  * XXX this interface doesn't really belong in here.  It is here because
  96.  * currently nsPipeInputStream is the only implementation of this interface.
  97.  */
  98. [scriptable, uuid(8C39EF62-F7C9-11d4-98F5-001083010E9B)] 
  99. interface nsISearchableInputStream : nsISupports
  100. {
  101.     /**
  102.      * Searches for a string in the input stream. Since the stream has a notion
  103.      * of EOF, it is possible that the string may at some time be in the 
  104.      * buffer, but is is not currently found up to some offset. Consequently,
  105.      * both the found and not found cases return an offset:
  106.      *    if found, return offset where it was found
  107.      *    if not found, return offset of the first byte not searched
  108.      * In the case the stream is at EOF and the string is not found, the first
  109.      * byte not searched will correspond to the length of the buffer.
  110.      */
  111.     void search(in string forString, 
  112.                 in boolean ignoreCase, 
  113.                 out boolean found,
  114.                 out unsigned long offsetSearchedTo);
  115. };
  116.  
  117. %{C++
  118.  
  119. /**
  120.  * NS_NewPipe2
  121.  *
  122.  * This function supercedes NS_NewPipe.  It differs from NS_NewPipe in two
  123.  * major ways:
  124.  *  (1) returns nsIAsyncInputStream and nsIAsyncOutputStream, so it is
  125.  *      not necessary to QI in order to access these interfaces.
  126.  *  (2) the size of the pipe is determined by the number of segments
  127.  *      times the size of each segment.
  128.  *
  129.  * @param pipeIn
  130.  *        resulting input end of the pipe
  131.  * @param pipeOut
  132.  *        resulting output end of the pipe
  133.  * @param nonBlockingInput
  134.  *        true specifies non-blocking input stream behavior
  135.  * @param nonBlockingOutput
  136.  *        true specifies non-blocking output stream behavior
  137.  * @param segmentSize
  138.  *        specifies the segment size in bytes (pass 0 to use default value)
  139.  * @param segmentCount
  140.  *        specifies the max number of segments (pass 0 to use default value)
  141.  *        passing PR_UINT32_MAX here causes the pipe to have "infinite" space.
  142.  *        this mode can be useful in some cases, but should always be used with
  143.  *        caution.  the default value for this parameter is a finite value.
  144.  * @param segmentAlloc
  145.  *        pass reference to nsIMemory to have all pipe allocations use this
  146.  *        allocator (pass null to use the default allocator)
  147.  */
  148. extern NS_COM nsresult
  149. NS_NewPipe2(nsIAsyncInputStream **pipeIn,
  150.             nsIAsyncOutputStream **pipeOut,
  151.             PRBool nonBlockingInput = PR_FALSE,
  152.             PRBool nonBlockingOutput = PR_FALSE,
  153.             PRUint32 segmentSize = 0,
  154.             PRUint32 segmentCount = 0,
  155.             nsIMemory *segmentAlloc = nsnull);
  156.  
  157. /**
  158.  * NS_NewPipe
  159.  *
  160.  * Preserved for backwards compatibility.  Plus, this interface is more
  161.  * amiable in certain contexts (e.g., when you don't need the pipe's async
  162.  * capabilities).
  163.  *
  164.  * @param pipeIn
  165.  *        resulting input end of the pipe
  166.  * @param pipeOut
  167.  *        resulting output end of the pipe
  168.  * @param segmentSize
  169.  *        specifies the segment size in bytes (pass 0 to use default value)
  170.  * @param maxSize
  171.  *        specifies the max size of the pipe (pass 0 to use default value)
  172.  *        number of segments is maxSize / segmentSize, and maxSize must be a
  173.  *        multiple of segmentSize.  passing PR_UINT32_MAX here causes the
  174.  *        pipe to have "infinite" space.  this mode can be useful in some
  175.  *        cases, but should always be used with caution.  the default value
  176.  *        for this parameter is a finite value.
  177.  * @param nonBlockingInput
  178.  *        true specifies non-blocking input stream behavior
  179.  * @param nonBlockingOutput
  180.  *        true specifies non-blocking output stream behavior
  181.  * @param segmentAlloc
  182.  *        pass reference to nsIMemory to have all pipe allocations use this
  183.  *        allocator (pass null to use the default allocator)
  184.  */
  185. inline nsresult
  186. NS_NewPipe(nsIInputStream **pipeIn,
  187.            nsIOutputStream **pipeOut,
  188.            PRUint32 segmentSize = 0,
  189.            PRUint32 maxSize = 0,
  190.            PRBool nonBlockingInput = PR_FALSE,
  191.            PRBool nonBlockingOutput = PR_FALSE,
  192.            nsIMemory *segmentAlloc = nsnull)
  193. {
  194.     PRUint32 segmentCount;
  195.     if (segmentSize == 0)
  196.         segmentCount = 0; // use default
  197.     else
  198.         segmentCount = maxSize / segmentSize;
  199.  
  200.     nsIAsyncInputStream *in;
  201.     nsIAsyncOutputStream *out;
  202.     nsresult rv = NS_NewPipe2(&in, &out, nonBlockingInput, nonBlockingOutput,
  203.                               segmentSize, segmentCount, segmentAlloc);
  204.     if (NS_FAILED(rv)) return rv;
  205.  
  206.     *pipeIn = in;
  207.     *pipeOut = out;
  208.     return NS_OK;
  209. }
  210.  
  211. %}
  212.